Skip to main content

Omnibridge

info

Legacy Omnibridge can be accessed at https://omni.legacy.gnosischain.com/bridge

Key Information​

Omnibridge is a native token bridge that mints the canonical representations of bridged assets on Gnosis. The Omnibridge is built on top of the Arbitrary Message Bridge (AMB) and thus relies on the same group of Trusted Bridge Validators and trust model as the AMB. With Telepathy added as the 8th validator, Omnibridge bridge is now more secure with trustless zero-knowledge light client technology. Check out how Omnibridge works with Telepathy validator here.

The Omnibridge currently connects Gnosis to Ethereum.

The Omnibridge mints bridged tokens using a variant of the ERC-677 token standard, with all bridged tokens tracked in the canonical Bridged Token Registries.

Overview​

Detail
Frontend URLhttps://omni.gnosischain.com
Trust Model4-of-8 Validator Multisig
Governance8-of-16 Multisig
Governance ParametersValidator Set, Daily Limits, Fees
Bug Bountyup to $2m
Bug ReportingImmunefi

Key Contracts​

Ethereum​

ContractEthereum Address
AMB Proxy Contract (Foreign)0x4C36d2919e407f0Cc2Ee3c993ccF8ac26d9CE64e
Omnibridge Multi-Token Mediator Proxy0x88ad09518695c6c3712AC10a214bE5109a655671
Validator Management Contract0xed84a648b3c51432ad0fD1C2cD2C45677E9d4064

Fees & Daily Limits​

TokenEthereum -> GnosisGnosis -> Ethereum
Approx. Gas Cost
Bridge Fees0%0.1%

Single Transaction Limits​

warning

Bridging DAI token to Gnosis Chain DOES NOT mint native xDai token. If you want native xDai, use the xDai Bridge

TokenEthereum -> GnosisGnosis -> Ethereum
Dai***1,000,000,0001,000,000,000 WXDAI
USDC1,000,000,00010,000,000
USDT1,000,000,0005,000,000
WETH690690
WBTC1212
GNO1835018350
GIV6000000060000000
CLNY1400000014000000
DXD10001000
HOPR70000007000000
HAUS120000120000

Daily Limits​

TokenEthereum -> GnosisGnosis -> Ethereum
Dai***1,000,000,000,000,000,0001,000,000,000,000,000,000 xDai
USDC1,000,000,000,000,000,00010,000,000
USDT1,000,000,000,000,000,0005,000,000
WETH690690
WBTC12.0000000112.00000001
GNO1835018350
GIV6000000060000000
CLNY1400000014000000
DXD10001000
HOPR70000007000000
HAUS120000120000

*** Bridging Dai Using Omnibridge

note

Daily Limit is reset according to the following logic: the smart contract stores total amount of processed tokens per current day and reverts on a new transfer if it exceeds the daily limit. Id of the day is calculated using the formula timestamp / (number of seconds in 1 day), where timestamp is the Unix timestamp.

Bridge Validators​

For a message/tokens to be relayed to another network, bridge validators need to affirm the transaction. Bridge validators are run by trusted members of the Gnosis community. Since Omnibridge is based on the Arbitrary Message Bridge functionality, the set of validators is the actual set of AMB validators. The same validator set is used as the AMB bridge, as the OmniBridge is built on top of the AMB Bridge.

Bridge Validator Flow​

Bridge Governance​

Bridge Design​

Ethereum -> Gnosis​

  1. Token spend approval by user.
  2. User call relayTokens() on Mediator contract.
  3. Mediator calls requireToPassMessage() on the Bridge.
  4. UserRequestForAffirmation event is emitted for validators to validate the message.
  5. Message is relayed to the mediator contract when consensus is met by calling executeAffirmation().
  6. ABM calls mediator on Gnosis chain:
    • token does not exist: the mediator deploys a new token registry and mints the relayed amount.
    • token exists: the relayed amount is minted in the token address.

Gnosis -> Ethereum.​

  1. User calls transferAndCall on ERC-677 token contract to send tokens to Omnibridge contract
  2. OnTokenTransfer is called
  3. Mediator contract burns tokens and calls bridge contract's requireToPassMessage() function.
  4. UseRequestForSignature event is emitted for validators to validate the message.
  5. Validators listen to the event: call submitSignature on Gnosis chain.
  6. CollectedSignatures event is emitted when consensus is met.
  7. User calls AMB (Ethereum side) executeSignatures()
  8. ABM calls handleBridgedTokens() on Mediator.
  9. Mediator contract unlocks the tokens

The Omnibridge is built on top of the Arbitrary Message Bridge.

Mediator Contracts​

To handle the approval of token transfers, the Omnibridge makes use of what is called a mediator contract.

  1. User calls token contract's approve() function to approve the balance to be transferred.
  2. relayTokens() is called on the Mediator contract
  3. Mediator calls transferFrom() on the token contract, transferring the approved balance
  4. If this is the first time that token is being bridged to the destination network, it will also query the token's name, symbol and decimals so a new contract can be deployed on the destination network
  5. Mediator contract then calls requireToPassMessage() on the bridge contract

Exceptions and Special Cases​

While most tokens can be freely transferred between chains, there are several exceptions where token properties create bridge-related issues.

  • Bridge operations are disabled for Rebasing tokens.
  • Inflationary tokens can still be bridged, but any accrued inflation IS NOT returned to the user upon bridge exit.

Rebasing Tokens​

Rebasing tokens include an elastic function where supply can be increased or decreased at regular intervals. If these tokens are bridged, supply impacts could result in inequities on either side of the bridge. In some cases this could result in a bridge balance reduction and the inability for users to exit. To prevent this, we have disabled bridging capability for rebasing type tokens. A partial token list is included below:

Click to View List
NameSymbolAddress
Base ProtocolBASE0x07150e919b4de5fd6a63de1f9384828396f25fdc
USDfUSDf0x05462671c05adc39a6521fa60d5e9443e9e9d2b9
xBTCXBTC0xecbf566944250dde88322581024e611419715f7a
DebaseDEBASE0x9248c485b0b80f76da451f167a8db30f33c70907
CoilCOIL0x3936ad01cf109a36489d93cabda11cf062fd3d48
DollarsUSDX0x2f6081e3552b1c86ce4479b80062a1dda8ef23e3
RMPLRMPL0xe17f017475a709de58e976081eb916081ff4c9d5
RebasedREB20x87f5f9ebe40786d49d35e1b5997b07ccaa8adbff
VELO TokenVLO0x98ad9b32dd10f8d8486927d846d4df8baf39abe2
Tokens of BabelTOB0x7777770f8a6632ff043c8833310e245eba9209e6
Rise ProtocolRISE0x3fa807b6f8d4c407e6e605368f4372d14658b38c
Soft LinkSLINK0x10bae51262490b4f4af41e12ed52a0e744c1137a
Ramifi ProtocolRAM0xac6fe9aa6b996d15f23e2e9a384fe64607bba7d5
GRPL FinanceGRPL0x15e4132dcd932e8990e794d1300011a472819cbd
Xdef FinanceXDEF20x5166d4ce79b9bf7df477da110c560ce3045aa889
AntiampleXAMP0xf911a7ec46a2c6fa49193212fe4a2a9b95851c27

Inflationary (Staking) Tokens​

Inflationary tokens accrue additional value over time. While they are locked in the bridge contract this value will accrue, but will remain on the balance of the bridge upon exit. Inflation will not be returned to a user's balance. This maintains the 1 to 1 ratio of bridged tokens necessary for OmniBridge functionality. Users are free to bridge these tokens but need to be aware that any accrued inflation will not be added to their balances. Usage of the accumulated inflation will be determined at a later time by bridge governors. A partial token list of inflationary tokens is included below:

Click to View List
NameSymbolAddress
Lido Staked EtherstETH0xae7ab96520de3a18e5e111b5eaab095312d7fe84
StakeHound Staked EtherSTETH0xdfe66b14d37c77f4e9b180ceb433d1b164f0281d
ankrETHAETH0xe95a203b1a91a908f9b9ce46459d101078c2c3cb
Cream ETH 2CRETH20xcbc1065255cbc3ab41a6868c22d1f1c573ab89fd
Binance ETH stakingBETH0x250632378e573c6be1ac2f97fcdf00515d0aa91b

Additional References:

Canonical Token Registries​

Multiple Representations​

In a multi-chain world, some assets (e.g. USDC) can be bridged over from different chains. This is because the two bridges create different representation of the token on Gnosis, even if the underlying asset is the same.

For example, there are two different representations of USDC on Gnosis:

AssetToken Contract
USDC from Ethereum0xDDAfbb505ad214D7b80b1f830fcCc89B60fb7A83
USDC from BSC0xD10Cc63531a514BBa7789682E487Add1f15A51E2

Gnosis adopts a naming convention where the "chain of origin" is added as a suffix to the token name (e.g. USDC from Ethereum, USDC from BSC)

Managing the Bridge​

Bridge administrators can perform 4 groups of operations with the xDai bridge. All operations are performed by owners of the Multisignature Wallet which requires several accounts to confirm the operation transaction.

NetworkMultisignature Wallet Address
ETH Mainnet0xff1a8EDA5eAcdB6aAf729905492bdc6376DBe2dd
Gnosis0x0d3726e5a9f37234d6b55216fc971d30f150a60f

Interacting with Bridge Contracts​

  1. One of the multisig wallet owners encodes the method call with a set of parameters (if any). For example, this can be done with the ABI Encoding Service.
  2. The encoded sequence of bytes is used to create a transaction for the multisig wallet contract. This is done with the submitTransaction() method of the multisig wallet contract. The method raises the event Submission containing the index of the registered transaction. The index is shared with the other owners of the wallet.
  3. The rest of the owners confirm the transaction by invoking confirmTransaction from the multisig wallet contract. As soon as enough confirmations are received, the method encoded in step 1 is invoked automatically. This is important because adequate gas limits must be set for that transaction and for the set of confirmations sent by the wallet owner finalizing the operation.
  4. If the method is not invoked because the gas limit is exceeded, the owners can execute the confirmed transaction manually by sending executeTransaction().
    This process can vary depending on the action being taken.

Upgrading Bridge Contract​

There are two possible scenarios for how the bridge or validators contracts can be upgraded:

  • Security fix when only the contract implementation is changed
  • Improvement when the contract implementation upgrade requires initialization of storage values.

A more detailed explanation can be found on the xDai Bridge page. The steps are the same but the contract addresses differ.

Managing Bridge Validators​

Bridge validators are separate from chain validators, and currently composed of a subset of Gnosis Chain validators. This is a dynamic set, as the bridge governors can vote to increase the current set as well as propose and vote on other bridge related measures.
After a ballot is finalized, the new validator is added to the bridge management multisignature wallets (one on each side of the bridge). The submitter will execute these methods: addValidator and (optionally if the voting threshold is to be changed) the setRequiredSignatures method. After encoding the data for each of these methods, it is sent to each contract (one on either side of the bridge) using the submitTransaction() execution method.

info

Before starting, current validators should determine:

  1. Who will add the new validator (the submitter)
  2. Coordinate a time when the other validators will confirm the transaction, as the bridge will be stopped to complete the upgrade.
  3. Ask the Omnibridge team to add a new bridge validator to the Certifier contract and confirm it has been added. This enables the node to relay bridge transactions with zero gas price.

Additional steps for setting up a validator node can be found in governance and here